Add an extension walkthrough #1572

plemarquand · 2025-05-21T18:07:57Z

Adds a walkthrough to the package.json that guides users through:

Installing Swift
Creating a New Project
Extension Commands
Running Tests
Selecting a Toolchain

Adds a walkthrough to the package.json that guides users through: - Installing Swift - Creating a New Project - Extension Commands - Running Tests - Selecting a Toolchain

rbenegal · 2025-05-29T02:26:10Z

package.json

+          {
+            "id": "installing-mac",
+            "title": "Installing Swift",
+            "description": "💻 Swift is cross-platform! If you already have Xcode installed, you're ready to go. Otherwise, see the instructions to [install on macOS](https://www.swift.org/install).\n🧑‍🤝‍🧑 Swift is [open source](https://github.com/swiftlang) and community driven!\n💬 Questions? Visit the [Swift forums](https://forums.swift.org/) for help.",


Ideas for the future:

Can possibly detect automatically if swift is already installed and skip this point if it is?

I think this is where the swiftly "Download Swift" command can go once the project is implemented

ya or link to install page on swift.org

rbenegal · 2025-05-29T02:29:36Z

package.json

+          }
+        ]
+      }
+    ],


Ideas for some other steps (some of these could be in their own section)

Project Panel

Useful settings (inlay hints come to mind so that the user is aware of the feature, possibly other useful settings as well)

Debugging

Project Panel

Documentation generation with DocC

Tips like hovering over the {} icon to see which swift version you're currently using

Maybe flag the environment and args settings and that they tie into all tasks?

package.json

rbenegal · 2025-05-29T02:34:21Z

assets/walkthrough/swiftToolchains.md

@@ -0,0 +1,10 @@
+The Swift extension automatically detects your installed Swift toolchain. However, it also provides a command called `Swift: Select Toolchain...` which can be used to select between toolchains if you have multiple installed.


Not sure if we can link to other pieces of documentation but perhaps we could link to some documentation on how the extension detects which toolchain it will use? I think the logic is a little tricky since it depends on things like environment variables, is swiftly installed, is Xcode installed etc.

rbenegal · 2025-05-29T02:35:37Z

assets/walkthrough/createNewProject.md

@@ -0,0 +1,12 @@
+There are several project templates to choose from:
+- `Library`: A package with a library. Use this to


Seems like this sentence is unfinished.

rbenegal · 2025-05-29T02:36:33Z

assets/walkthrough/createNewProject.md

@@ -0,0 +1,12 @@
+There are several project templates to choose from:


Would be cool if there was some way we could just generate this from the code. I feel like we'll forget to update this page if we change the template options in the future.

I agree, but these descriptions aren't going to 1:1 match the ones from SwiftPM's help documentation so we'd need to craft a description for each one by hand anyway.

award999

amazing start, here are some thoughts

award999 · 2025-05-29T15:17:42Z

assets/walkthrough/swiftToolchains.md

+
+You may be prompted to select where to configure this new path. Your options are to:
+
+- Save it in User Settings


similar to what is done for command names, we should show button text as Save it in User Settings and Save in Workspace Setting

award999 · 2025-05-29T15:18:08Z

assets/walkthrough/swiftToolchains.md

+- Save it in User Settings
+- Save it in Workspace Settings
+
+Keep in mind that Workspace Settings take precedence over User Settings.


Maybe for the User Settings tab name too?

award999 · 2025-05-29T15:19:32Z

package.json

+          {
+            "id": "installing-mac",
+            "title": "Installing Swift",
+            "description": "💻 Swift is cross-platform! If you already have Xcode installed, you're ready to go. Otherwise, see the instructions to [install on macOS](https://www.swift.org/install).\n🧑‍🤝‍🧑 Swift is [open source](https://github.com/swiftlang) and community driven!\n💬 Questions? Visit the [Swift forums](https://forums.swift.org/) for help.",


The open source and Swift forums mentions and links I think we should take out of the install, maybe leave it as a final Get Help step. Seems a little noisy here

award999 · 2025-05-29T15:19:55Z

package.json

+          {
+            "id": "installing-mac",
+            "title": "Installing Swift",
+            "description": "💻 Swift is cross-platform! If you already have Xcode installed, you're ready to go. Otherwise, see the instructions to [install on macOS](https://www.swift.org/install).\n🧑‍🤝‍🧑 Swift is [open source](https://github.com/swiftlang) and community driven!\n💬 Questions? Visit the [Swift forums](https://forums.swift.org/) for help.",


ya or link to install page on swift.org

award999 · 2025-05-29T15:20:25Z

package.json

+          {
+            "id": "installing-mac",
+            "title": "Installing Swift",
+            "description": "💻 Swift is cross-platform! If you already have Xcode installed, you're ready to go. Otherwise, see the instructions to [install on macOS](https://www.swift.org/install).\n🧑‍🤝‍🧑 Swift is [open source](https://github.com/swiftlang) and community driven!\n💬 Questions? Visit the [Swift forums](https://forums.swift.org/) for help.",


technically command line tools works too for people who don't want Xcode

award999 · 2025-05-29T15:21:14Z

package.json

+          {
+            "id": "swift-commands",
+            "title": "Swift Commands",
+            "description": "🎨 Explore the commands available in the command palette prefixed with \"> Swift:\". You can use the command palette to run any of the commands provided by the Swift extension.\n[Open Command Palette](command:workbench.action.showCommands)",


Can we create our own Show Swift Commands... command that wraps await vscode.commands.executeCommand("workbench.action.quickOpen", "> Swift:");

award999 · 2025-05-29T15:21:46Z

package.json

+          {
+            "id": "testing",
+            "title": "Running Tests",
+            "description": "✅ Tests are automatically discovered in your project and added to the [Testing View](https://code.visualstudio.com/docs/debugtest/testing#_automatic-test-discovery-in-testing-view).\n🧪 Both [XCTest](https://developer.apple.com/documentation/xctest) and [Swift Testing](https://developer.apple.com/xcode/swift-testing/) tests are supported.",


maybe command to run all tests or use one of the add test target refactorings?

award999 · 2025-05-29T15:22:47Z

package.json

+          }
+        ]
+      }
+    ],


Maybe flag the environment and args settings and that they tie into all tasks?

plemarquand added 3 commits May 21, 2025 14:06

Add an extension walkthrough

116cb6b

Adds a walkthrough to the package.json that guides users through: - Installing Swift - Creating a New Project - Extension Commands - Running Tests - Selecting a Toolchain

Ensure assets are added to .vsix

1f19fef

Properly theme swiftCommands.svg

541c055

rbenegal reviewed May 29, 2025

View reviewed changes

award999 reviewed May 29, 2025

View reviewed changes

Fixup wording

5e97377

		@@ -0,0 +1,10 @@
		The Swift extension automatically detects your installed Swift toolchain. However, it also provides a command called `Swift: Select Toolchain...` which can be used to select between toolchains if you have multiple installed.

		@@ -0,0 +1,12 @@
		There are several project templates to choose from:
		- `Library`: A package with a library. Use this to


		You may be prompted to select where to configure this new path. Your options are to:

		- Save it in User Settings

Add an extension walkthrough #1572

Are you sure you want to change the base?

Add an extension walkthrough #1572

Uh oh!

Conversation

plemarquand commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

award999 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

plemarquand commented May 21, 2025 •

edited

Loading